iT邦幫忙

2024 iThome 鐵人賽

DAY 10
0
Software Development

Spring boot 從零到寫出ChatGPT系列 第 10

Spring boot 從零開始 (10) - 如何利用Swagger快速生成API文件

  • 分享至 

  • xImage
  •  

Hello ~ 大家好,經過了前面幾天的練習後,是不是可以慢慢開發出API了呢 ?

那如果我們API愈來愈多,或是後端團隊要提供給前端團隊API文件,又或著是要跟其他跨單位合作的話,我們除了自己撰寫API文件,還有沒有其他更好的方式呢 ?!

這時候真的是讚嘆Swagger的發明,真的是後端人員的福音 /images/emoticon/emoticon37.gif
所以我們接著就要來介紹甚麼是Swagger,跟我們如何應用她來快速生成文件了 ~~~

Swagger和OpenAPI

如官網文件所說,Swagger 是一套功能強大且易於使用的 API 開發工具,適用於團隊和個人,支援從設計和文件到測試和部署的整個 API 生命週期的開發。
而它的歷史,Swagger 是一間名為SmartBear Software 的公司,開發出的REST API 的工具,可以幫助設計、構建、記錄和使用REST API,後來貢獻給OpenAPI Initiative,並公開讓所有人都能夠使用。

Spring boot 如何使用Swagger/OpenAPI

因為我們已經使用Spring boot3.3.0的版本,所以建議搭配以下版本來使用,
pom.xml加入以下dependency

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

接著我們可以設定application.properties ,也可以維持原本預設值

# /api-docs endpoint custom path
springdoc.api-docs.path=/api-docs
# 自訂義swagger-ui網址
springdoc.swagger-ui.path=

其他各詳細的部分,我們可以參考官網設定喔!

那如果甚麼設定都不改的話,我們可以直接在dependency加入後,啟動Application,輸入
http://localhost:8080/swagger-ui/index.html 就可以看到自動生成的API文件的UI介面👇
https://ithelp.ithome.com.tw/upload/images/20240924/201121184wcxE1r9RD.png

如果甚麼都沒有設定的話,也許會少了一些描述,所以我們接著再來介紹幾個常用的Annotation,讓我們生成的文件更加完整吧 ~

常見的Annotation

@Tag : 可以針對Controller命名跟描述

  • 範例: 可以看到可以給予名稱和描述
@Tag(name = "IronMan Demo Service",description = "provide to demo bookStore service")

@Operation : 用來描述單一的URL

  • 範例 : 可以針對該API定義命稱與描
@Operation(summary = "Gets book by ID", description= "Book must exist")

@ApiResponses & @ApiResponse : 可以針對API回傳的結果和http status code進行說明

  • 範例
    @ApiResponses(value = {
            @ApiResponse(responseCode = "20", description = "Success to find book"),
            @ApiResponse(responseCode = "404", description = "Book not found")})

接著我們再重新看一次剛剛我們有多加說明的API在Swagger的樣貌吧~
https://ithelp.ithome.com.tw/upload/images/20240924/20112118AtjJgu6DWx.png

是不是變得更完整呢 ?!
未來就可以寫完程式也就一起連同API文件一起完成了 /images/emoticon/emoticon08.gif

參考文件


上一篇
Spring boot 從零開始 (9) - RESTful API跟Spring boot annotation介紹
下一篇
Spring boot 從零開始 (11) - Spring Data JPA讓資料庫處理變得更輕鬆 (上集)
系列文
Spring boot 從零到寫出ChatGPT30
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言